Skip to content

feat(shift-manager): the directory screens read the Lab's views and collections, not the snapshot (FIX-2775) - #5492

Draft
jhoffner wants to merge 25 commits into
mainfrom
fix-2775-screen-migration
Draft

jhoffner wants to merge 25 commits into
mainfrom
fix-2775-screen-migration

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

Most of Shift Manager's screens still draw from one snapshot the browser builds by reading the whole Lab. Roster, the sidebar's TEAMS, PROJECTS and counts, Jump to, a project, Messages, Routines, Usage, Settings and the worker rows on every other screen see a change only on the next whole-Lab read. A worker's on-shift square can disagree with the Inbox for the same ask, because they come from two different reads. Retry and R read the whole Lab again. The snapshot can't be deleted (FIX-2777) while any screen still reads it.

What this does

Every screen reads through the package reads instead, and none reads the snapshot:

  • The worker directory is one shared read per page: the organization's inventory, read whole, joined with the user's roster (D1). Status and counts come from the Inbox view's workerId, so a worker's square and the Inbox move in the same update.
  • Projects, messages, a project's workstreams read whole and stay current through react's useResource(def, { all: true }) (PR 1).
  • Routines, Usage, the project setup read their views live, not once per Lab read.
  • The gate (refused or unreachable) is workforce's organization(), with the same pages and words.
  • Retry and R read again what the screen holds: the directory, the Inbox view, and every read a mounted screen registered (the message log, a project's workstreams, its report and setup, Routines, Usage).
  • The frame waits for the directory's first reads (inventory, roster, session list, projects). A first session list that fails is the couldn't-reach page, never "no sessions".

readEveryScopeEntry is gone, the 16 allowlist entries are gone, and no file outside FIX-2777's four imports reads.ts. Conversation.tsx's answered and lab-data.tsx's noteAnswered are gone: the feed is live.

This is PR 3 of 3 (PR 1 #5470 react, PR 2 #5477 workforce).

What's asked of you

This implements the approved direction. One goal leg the spec names is not in this PR (see Parts worth reviewing closely, last item); say whether it should block the merge. Codex's fourth point (two person stops with the same explicit id in two requests collide in the Inbox) is an older orchestration defect, being filed on its own; its thread stays open.

Parts worth reviewing closely

  • Status from the Inbox view (src/lib/shift.ts, workerStates). Riskiest change: every screen that draws a status or a count reads it. A worker's asks are the view's suspension holds by the workerId the view stamped; held tasks are the view's tasks resolved by workerFor. The new one answer leg of it-shows-who-is-on-shift grades it in Chromium: every committed page state has the Inbox listing the ask exactly when the square reads on shift.
  • One read per page (src/lib/directory.tsx, directory-reads.ts): DirectoryProvider holds the inventory, roster, session list and projects reads once; screens read useWorkers, useSessions, useProjects. The frame waits for the directory's first reads (useDirectoryLanded) as it waited for the snapshot. A 404 on a projects scope reads as no projects; a 404 or empty inventory is the "no inventory" failure in today's words.
  • The gate (src/lib/gate.ts): 401, 403, a Lab with no roster flow (the engine's exact unknown-flow message), or an identity naming no organization is the refusal; anything else is unreachable, and Retry asks again. The decision comes from the server's identity read, never from caller input (BP-031).
  • R (src/lib/page-reads.tsx): each screen read registers its read-again while mounted, and R reads every one. Without it, the message log and a project's entries stopped re-reading on R once they left the snapshot's readAt (realtime/app-views-read-on-notice a:lab-read caught it).
  • One definition per moved name: reads.ts imports Failure, Section, Worker, Project and BoardTaskView from their new modules instead of re-exporting them. derive.ts drops its snapshot workerStates. Project and toProject live in a leaf project.ts, which breaks the lab-data → reads → projects → lab-data cycle. Five reads.ts type entries leave the allowlist (FIX-2777's share goes 21 → 16), and the census's built check now holds that share at most 21, not exactly 21.
  • The snapshot still reads (FIX-2777 deletes it). Nothing draws from it; the connection bar still counts it. The shell.test.tsx refusal test therefore sees two refused reads, the gate's and the snapshot's own.
  • react: held matches its baseline by a read-mode string (all:<prefix> or page), not how's identity; the topicPrefix live path narrowing is pinned by two tests (feat(react): useResource reads a whole collection, with failure and refresh (FIX-2775, 1/3) #5470's review).
  • Not done here: the directory live leg of its-summary-changes-on-its-own (a routine paused and a project added from another session show within 2 s). It needs a projects flow and a routine with a working schedule added to that goal's headless host. It moves to FIX-2777: its "no snapshot read" half can only be graded once FIX-2777 removes the snapshot's own live read, and FIX-2777 isn't done until the leg passes. Today's coverage of the same path: realtime/app-views-read-on-notice (a project's entries and the message log from another client) and directory.test.tsx (a hire from another tab, one read per notice).

Spec: specs/issues/FIX-2775/ (D1) · Linear: FIX-2775 · Epic: FIX-2683 · PR 3 of 3 (PR 1: #5470, PR 2: #5477) · This PR merges.

How to review this

How to review this. This implements an approved spec. The approach and the numbered decisions in its DECISIONS.md are already signed off by a human, so please review the code against that direction, not the direction itself. The canonical set is retained at specs/issues/FIX-2775/ on main. Linear links to it and to the original merged spec PR, which keeps the review history. Follow-up amendment PRs explain later direction changes. Current architecture docs remain the authority for shipped behavior (BP-037).

Most valuable here: correctness on the second path (the legacy shape, the null boundary, the concurrent case, the cancel path), anything deriving an auth or routing decision from caller-controllable input, and a behaviour the tests assert around rather than on.

Already settled upstream: the approach and every decision in the spec's DECISIONS.md (human-approved: if one is wrong, say so as a spec finding and it gets folded back; don't re-argue it inline), and the conventions in docs/contributing/best-practices.md.

Engineering calls
  • reads.ts helpers moved to screen modules so FIX-2777 deletes four files and edits none: failure.ts (Failure, describeFailure, Section), workers.ts (Worker, toWorker, workerNames, GENERAL_TEAM), boards.ts (the board refs), projects.ts (Project, toProject), shift.ts (status, teams, the Shift Coordinator), documents.ts (Jump to's documents, one manifest read per worker flow, cached by flow).
  • failureOf on react/internal, so a write's refusal is worded as useView's and useResource's failure are. Internal only; no public name.
  • The frame waits for the directory's first reads, not only the gate, so no screen draws half a directory; the roster isn't waited for (a screen says when it hasn't loaded).
  • Keys bound in useLayoutEffect, so R or [ pressed the moment the frame draws is heard.
  • Names: the directory's reads say values and entries, never rows (the retired-terms check).
  • Goal controls retargeted from derive.ts / reads.ts to shift.ts, directory.tsx and directory-reads.ts.
Everything else

Goal check (node specs/issues/FIX-2775/poc/directory-census/check.mjs):

  • --built: PASS. "census: 0 sites on 0 lines in 0 files · files that import reads.ts outside FIX-2777's four: 0", allowlist 16 entries, all FIX-2777's.
  • --simulate-built: PASS, same counts.
  • --control: FAIL (expected). It names the planted entry ("allowlist entry unclassified: src/lib/planted.ts Planted (type)") and the planted site ("the census finds 1 sites").

Red, then green.

Check Red Green
it-shows-who-is-on-shift one answer GOAL_CONTROL=status-from-snapshot (status from the snapshot's walked asks, as on main): "eng.spare's approval: 1 of 3 drawn states disagree, the first {"count":"3","status":"off shift","listed":true}", and after Approve "1 of 8 drawn states disagree" As written: PASS, "listed and its square on shift in one update, over 3 drawn states; after Approve both cleared together, over 6"
The goal's other controls ignore-asks fails status; count-queued fails slots and holding Both spreads PASS
react topicPrefix live paths Narrowing removed: the first test fails ("expected [ …(2) ] to have a length of 1 but got 2"); narrowing to the whole prefix: the mid-segment test fails 10 of 10
react held by read mode No red: the reading guard already keeps a stale baseline out, so this is the hardening #5470's review asked for, not a behaviour change. Dropping the mode check fails no test 52 of 52 in useResource*
usage.test.ts Slept 20 ms for the second answer Waits on a count of the fake's settled answers, then flushes the hook
R reads each screen's reads (page-reads.test.tsx) "expected [ 1, 1 ] to deeply equal [ 2, 2 ]"; goal a:lab-read: "Shift Manager message log read never after a Lab read" Test passes; goal PASS, "message log 0 ms, project entries 0 ms"
A failed first session list (directory.test.tsx) No failure on the sessions; a drawn [] Lands as its failure; a refresh that lands clears it
The frame waits for the roster (directory.test.tsx) "expected true to be false" (landed before the roster) Lands only once the roster does
Jump to's documents (documents.test.tsx) "expected { ok: true, value: [ { …(2) } ] } to be undefined" Unread while a new flow's manifest is read
Fallow audit (pnpm fallow:audit --base origin/main) "✗ 1 export · 5 duplicate pairs · 1 circular dependency" Exit 0, dead code 0
Goals typecheck "optimistic-reply.ts(22,15): … declares 'Worker' locally, but it is not exported" Clean

Checks, run with the FSDEV_* model variables unset:

  • packages/shift-manager npx vitest run, twice on the current head: 104 files, 767 passed, 5 skipped, both times (with the pages built; command.test.ts needs dist-client).
  • packages/shift-manager npx vitest run inventory: 2 files, 5 tests pass.
  • packages/react npx vitest run: 64 files, 617 tests.
  • npx tsc --noEmit -p .: packages/react (and tsconfig.test.json), packages/shift-manager, goals: clean.
  • pnpm lint: clean. check-retired-terms (tree and --added-since) and the vocabulary sweep: PASS.
  • pnpm fallow:new-dead-code origin/main: no issues. pnpm fallow:audit --base origin/main: exit 0.
  • Goals run, model-free: PASS for it-shows-who-is-on-shift (its three controls FAIL as required), its-summary-changes-on-its-own, realtime/app-views-read-on-notice, it-sends-a-turn-into-a-worker-session and it-opens-a-lab. it-opens-a-lab failed twice before its title check waited for the task's row, which lands 14 to 22 ms after the frame draws.
  • Not graded here: it-shows-and-stops-a-task-run needs the devtool's pages built ("served no devtool; build its pages with pnpm build:assets"). it-shows-worker-token-usage and a-task-shows-its-model-and-tokens don't boot their Lab: the Claude Code harness refuses their scripted SDK ("its version can't be read (its manifest could not be located)"), and on their documented command @/lib doesn't resolve through lab-data.tsx, as on main. The model goals were not run.

Changeset: .changeset/shift-manager-directory-follows-changes.md, @flow-state-dev/shift-manager patch. Docs line: packages/shift-manager/README.md, written at release.

https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa


Generated by Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
…X-2775)

harnessRead slept 20 ms for whichever of Re-check and the view landed second.
The fake now counts each answer as it settles, and the helper waits for both,
then flushes the hook's update.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
…s, not rows (FIX-2775)

The pre-push retired-terms check reads 21 new row names on this branch: the
whole-collection read's parsed values, the parsers' arguments and the test
fixtures. Renamed to values, entries or the thing itself (a task, the stored
entries); no behaviour changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
…s, not rows (FIX-2775)

The tree-wide retired-terms check counted three row lines and one member name
this branch moved or wrote.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
…(FIX-2775)

it-shows-who-is-on-shift gains the leg the spec names: a worker off shift stops
for an approval, then it is approved from Inbox, and in every state the page
draws (a MutationObserver per committed change) the Inbox lists the ask
exactly when the worker's TEAMS square is on shift. The control counts the
snapshot's walked asks for status while the Inbox lists the view's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
… string; goal.md names the leg (FIX-2775)

tsx names a function's inner helpers with __name, which the page doesn't have,
so the recorder goes into the page as a string.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 20, 2026 2:50am UTC
flow-state-dev-docs Ready Ready Preview Nov 20, 2026 2:50am UTC
1 Skipped Deployment
Project Deployment Actions Updated
flow-state-dev-ui Ignored Ignored Preview Nov 20, 2026 2:50am UTC

Request Review

@linear-code

linear-code Bot commented Nov 20, 2026

Copy link
Copy Markdown

FIX-2775

Copy link
Copy Markdown
Collaborator Author

@codex review

Riskiest change: status and counts now come from the Inbox view (packages/shift-manager/src/lib/shift.ts, workerStates), which every screen that draws a status or a count reads. A worker's asks are the view's suspension holds by the workerId the view stamped, and its held tasks are the view's tasks resolved by workerFor. Please check whether an ask or a task can count for the wrong worker, or for none, compared with the old rule in derive.ts (a running task, or an ask in a session that names the worker).

Second: the gate in src/lib/gate.ts (which failures are a refusal versus an unreachable Lab), and DirectoryProvider in src/lib/directory.tsx (one inventory, roster, session-list and projects read per page; the frame waits for them).


Generated by Claude Code

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-20T01:44:12.144814Z 8ee63f4 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown
Contributor

Mechanism check (advisory, never blocks)

Rows from docs/mechanisms/mechanisms.yaml · labels: none

New export Package Mechanism
failureOf @flow-state-dev/react react

@gitar-bot

gitar-bot Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Note

Automatic reviews are paused because your team has used its included automatic processing for this billing period (headroom scales with your seat count). You can still comment "Gitar review" to run one anytime, and automatic reviews resume on their own by December 1. Add seats for more headroom.
Learn more

Code Review ✅ Approved 🔴 High risk

Moving worker status and counts across all screens to the shared Inbox view could make shift indicators and staffing totals broadly incorrect.

Moves Shift Manager's directory screens onto the package reads, so roster, sidebar, Jump to, projects, messages, routines, usage and settings all read live views and collections instead of the whole-Lab snapshot, with status and counts drawn from the Inbox view's workerId. No issues found.

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

Auto-approval Not enabled

Set up

Was this helpful? React with 👍 / 👎 | Gitar

With the screens off the snapshot, R read the Inbox view, the directory and
the projects, but not the message log, a project's workstreams, its report,
the project setup, Routines or Usage: on main those re-read on each Lab read's
readAt. Each of those reads now registers its read-again with the page
(page-reads.tsx) while mounted, and R reads every one. Caught by
realtime/app-views-read-on-notice a:lab-read, retargeted from the snapshot's
Refresh to R. page-reads.test.tsx was red before the hooks registered
(expected [1, 1] to deeply equal [2, 2]).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8ee63f43e0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/shift-manager/src/lib/shift.ts Resolved
…o dead export (FIX-2775)

Fallow's audit on the PR found three things this branch left:

- reads.ts kept alias exports of Failure, Section, Worker, Project and
  BoardTaskView beside their new homes, and derive.ts kept its snapshot
  workerStates, WorkerState(s) and Roster beside shift.ts's. reads.ts now
  imports the moved names; derive.ts drops the snapshot status, which no
  screen reads (its one test case goes with it).
- lab-data -> reads -> projects -> lab-data: the snapshot reader parsed projects
  through projects.ts, which holds hooks. Project, ProjectVisibility and
  toProject move to a leaf, project.ts.
- StatusWord in ui.tsx had no caller; PartialMark and ShiftMark were imported
  and unused in ShiftCoordinator.tsx.

The inventory allowlist loses the five reads.ts type entries that no longer
exist, and Project's screen-type reason moves with it to project.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
…775)

The goals typecheck failed on optimistic-reply.ts, which imported Worker from
reads.ts after it moved. sent-line-rises-reply-stays's Shift Manager page
imported toWorker from reads.ts too (a page copied into the package, outside
the goals typecheck); its fake Lab drops the answered field Shift Manager no
longer has.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
…ssion list, and Jump to drops stale documents (FIX-2775)

From Codex's review of #5492:

- A first session list that failed landed as an empty list, so every screen
  drew no sessions. The directory now keeps the last list that landed and the
  failure apart; a failed first list is the couldn't-reach page with Retry, as
  a failed first whole-Lab read was.
- The frame drew before the roster watch landed, so the inventory's workers
  showed and then the user's own joined them. The directory has not landed
  until the roster has.
- Jump to showed the previous flow set's documents while a new flow's manifest
  was read. It is unread until the read for the current flows lands.

Each was red first: directory.test.tsx ('the given combination of arguments
(undefined and string) is invalid', 'expected true to be false'),
documents.test.tsx ('expected { ok: true, value: [ { …(2) } ] } to be
undefined').

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
…ever grow

Moving Failure, Section, Worker, Project and BoardTaskView out of reads.ts
leaves one definition each, so their five reads.ts type entries went with them
(21 -> 16). The built check held FIX-2777's count equal to main's; it now holds
it at most main's, as the inventory test holds the whole allowlist. The
pre-implementation count is unchanged. The inventory settings name Sessions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
…e its row lands (FIX-2775)

The frame titles a task by its id until its row is read (a session read and
the board's view, 14-22 ms here), and the check read the title as the frame
drew. It now waits for a title other than the id, at most 20 s, then grades it
against the store as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa
Conversation.tsx: keep main's conversationLines model for the feed, and
this branch's removal of the snapshot's answered-ask reread.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGfuuX5mPxVeUwVXfa

This branch was successfully deployed

1 active deployment
Preview – flow-state-dev-docs — d7977750 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants